/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
/* vim:set et sts=4: */
/* IBust - IBus with Traditional interface
 * Copyright(c) 2013 Daniel Sun
 * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
 * Copyright (C) 2008-2010 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#if !defined (__IBUST_H_INSIDE__) && !defined (IBUST_COMPILATION)
#error "Only <ibust.h> can be included directly"
#endif

/**
 * SECTION: ibustshare
 * @short_description: Shared utility functions and definition.
 * @stability: Stable
 *
 * This file defines some utility functions and definition
 * which are shared among ibust component and services.
 */

#ifndef __IBUST_SHARE_H_
#define __IBUST_SHARE_H_

#include <glib.h>

/**
 * IBUST_SERVICE_IBUST:
 *
 * Address of IBust service.
 */
#define IBUST_SERVICE_IBUST       "org.freedesktop.IBust"

/**
 * IBUST_SERVICE_PANEL:
 *
 * Address of IBust panel service.
 */
#define IBUST_SERVICE_PANEL      "org.freedesktop.IBust.Panel"

/**
 * IBUST_SERVICE_CONFIG:
 *
 * Address of IBust config service.
 */
#define IBUST_SERVICE_CONFIG     "org.freedesktop.IBust.Config"

/**
 * IBUST_SERVICE_NOTIFICATIONS:
 *
 * Address of IBust notification service.
 */
#define IBUST_SERVICE_NOTIFICATIONS    "org.freedesktop.IBust.Notifications"

/**
 * IBUST_PATH_IBUST:
 *
 * D-Bus path for IBust
 */
#define IBUST_PATH_IBUST          "/org/freedesktop/IBust"

/**
 * IBUST_PATH_FACTORY:
 *
 * D-Bus path for IBust factory.
 */
#define IBUST_PATH_FACTORY       "/org/freedesktop/IBust/Factory"

/**
 * IBUST_PATH_PANEL:
 *
 * D-Bus path for IBust panel.
 */
#define IBUST_PATH_PANEL         "/org/freedesktop/IBust/Panel"

/**
 * IBUST_PATH_CONFIG:
 *
 * D-Bus path for IBust config.
 */
#define IBUST_PATH_CONFIG        "/org/freedesktop/IBust/Config"

/**
 * IBUST_PATH_NOTIFICATIONS:
 *
 * D-Bus path for IBust notifications.
 */
#define IBUST_PATH_NOTIFICATIONS "/org/freedesktop/IBust/Notifications"

/**
 * IBUST_PATH_INPUT_CONTEXT:
 *
 * Template of D-Bus path for IBust input context.
 */
#define IBUST_PATH_INPUT_CONTEXT "/org/freedesktop/IBust/InputContext_%d"

/**
 * IBUST_INTERFACE_IBUST:
 *
 * D-Bus interface for IBust.
 */
#define IBUST_INTERFACE_IBUST     "org.freedesktop.IBust"

/**
 * IBUST_INTERFACE_INPUT_CONTEXT:
 *
 * D-Bus interface for IBust input context.
 */
#define IBUST_INTERFACE_INPUT_CONTEXT \
                                "org.freedesktop.IBust.InputContext"

/**
 * IBUST_INTERFACE_FACTORY:
 *
 * D-Bus interface for IBust factory.
 */
#define IBUST_INTERFACE_FACTORY  "org.freedesktop.IBust.Factory"

/**
 * IBUST_INTERFACE_ENGINE:
 *
 * D-Bus interface for IBust engine.
 */
#define IBUST_INTERFACE_ENGINE   "org.freedesktop.IBust.Engine"

/**
 * IBUST_INTERFACE_PANEL:
 *
 * D-Bus interface for IBust panel.
 */
#define IBUST_INTERFACE_PANEL    "org.freedesktop.IBust.Panel"

/**
 * IBUST_INTERFACE_CONFIG:
 *
 * D-Bus interface for IBust config.
 */
#define IBUST_INTERFACE_CONFIG   "org.freedesktop.IBust.Config"

/**
 * IBUST_INTERFACE_NOTIFICATIONS:
 *
 * D-Bus interface for IBust notifications.
 */
#define IBUST_INTERFACE_NOTIFICATIONS    "org.freedesktop.IBust.Notifications"

G_BEGIN_DECLS

/**
 * ibust_get_local_machine_id:
 * @returns: A newly allocated string that shows the UUID of the machine.
 *
 * Obtains the machine UUID of the machine this process is running on.
 */
const gchar     *ibust_get_local_machine_id
                                        (void);

/**
 * ibust_set_display:
 * @display: Display address, as in DISPLAY environment for X.
 *
 * Set the display address.
 */
void             ibust_set_display       (const gchar    *display);

/**
 * ibust_get_address:
 * @returns: D-Bus address of IBust. %NULL for not found.
 *
 * Return the D-Bus address of IBust.
 * It will find the address from following source:
 * <orderedlist>
 *    <listitem><para>Environment variable IBUST_ADDRESS</para></listitem>
 *    <listitem><para>Socket file under ~/.config/ibust/bus/</para></listitem>
 * </orderedlist>
 *
 * See also: ibust_write_address().
 */
const gchar     *ibust_get_address       (void);

/**
 * ibust_write_address:
 * @address: D-Bus address of IBust.
 *
 * Write D-Bus address to socket file.
 *
 * See also: ibust_get_address().
 */
void             ibust_write_address     (const gchar    *address);

/**
 * ibust_get_user_name:
 * @returns: A newly allocated string that stores current user name.
 *
 * Get the current user name.
 * It is determined by:
 * <orderedlist>
 *    <listitem><para>getlogin()</para></listitem>
 *    <listitem><para>Environment variable SUDO_USER</para></listitem>
 *    <listitem><para>Environment variable USERHELPER_UID</para></listitem>
 *    <listitem><para>Environment variable USERNAME</para></listitem>
 *    <listitem><para>Environment variable LOGNAME</para></listitem>
 *    <listitem><para>Environment variable USER</para></listitem>
 *    <listitem><para>Environment variable LNAME</para></listitem>
 * </orderedlist>
 */
const gchar     *ibust_get_user_name     (void);

/**
 * ibust_get_daemon_uid:
 * @returns: UID of ibust-daemon; or 0 if UID is not available.
 *
 * Get UID of ibust-daemon.
 *
 * Deprecated: This function has been deprecated and should
 * not be used in newly written code.
 */
glong            ibust_get_daemon_uid    (void) G_GNUC_DEPRECATED;

/**
 * ibust_get_socket_path:
 * @returns: A newly allocated string that stores the path of socket file.
 *
 * Get the path of socket file.
 */
const gchar     *ibust_get_socket_path   (void);

/**
 * ibust_get_timeout:
 * @returns: A GDBus timeout in milliseconds. -1 when default timeout for GDBus should be used.
 *
 * Get the GDBus timeout in milliseconds. The timeout is for clients (e.g. im-ibust.so), not for ibust-daemon.
 * Note that the timeout for ibust-daemon could be set by --timeout command line option of the daemon.
 */
gint             ibust_get_timeout       (void);

/**
 * ibust_free_strv:
 * @strv: List of strings.
 *
 * Free a list of strings.
 * Deprecated: This function has been deprecated and should
 * not be used in newly written code.
 */
void             ibust_free_strv         (gchar          **strv)
    G_GNUC_DEPRECATED;

/**
 * ibust_key_event_to_string:
 * @keyval: Key symbol.
 * @modifiers: Modifiers such as Ctrl or Shift.
 * @returns: The name of a key symbol and modifier.
 *
 * Return the name of a key symbol and modifiers.
 *
 * For example, if press ctrl, shift, and enter, then this function returns:
 * Shift+Control+enter.
 */
const gchar     *ibust_key_event_to_string
                                        (guint           keyval,
                                         guint           modifiers);

/**
 * ibust_key_event_from_string:
 * @string: Key event string.
 * @keyval: Variable that hold key symbol result.
 * @modifiers: Variable that hold modifiers result.
 * @returns: TRUE for succeed; FALSE if failed.
 *
 * Parse key event string and return key symbol and modifiers.
 */
gboolean         ibust_key_event_from_string
                                        (const gchar    *string,
                                         guint          *keyval,
                                         guint          *modifiers);

/**
 * ibust_init:
 *
 * Init the ibust types.
 *
 * It is actually a wrapper of g_type_init().
 */
void             ibust_init              (void);

/**
 * ibust_main:
 *
 * Runs an IBust main loop until ibust_quit() is called in the loop.
 *
 * See also: ibust_quit().
 */
void             ibust_main              (void);

/**
 * ibust_quit:
 *
 * Stops an IBust from running.
 *
 * Any calls to ibust_quit() for the loop will return.
 * See also: ibust_main().
 */
void             ibust_quit              (void);

/**
 * ibust_set_log_handler:
 * @verbose: TRUE for verbose logging.
 *
 * Sets GLIB's log handler to ours. Our log handler adds time info
 * including hour, minute, second, and microsecond, like:
 *
 * (ibust-daemon:7088): IBUST-DEBUG: 18:06:45.822819: ibust-daemon started
 *
 * If @verbose is %TRUE, all levels of messages will be logged. Otherwise,
 * DEBUG and WARNING messages will be ignored.  The function is used in
 * ibust-daemon, but can be useful for IBust client programs as well for
 * debugging. It's totally fine for not calling this function. If you
 * don't set a custom GLIB log handler, the default GLIB log handler will
 * be used.
 */
void             ibust_set_log_handler   (gboolean verbose);

/**
 * ibust_unset_log_handler:
 *
 * Remove the log handler which is set by ibust_set_log_handler.
 */
void             ibust_unset_log_handler (void);

G_END_DECLS
#endif
